lab components / Actions and controls

Period picker

Allow users to select a range of dates quickly and intuitively.

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { PeriodPicker } from "@siteimprove/fancylab";

#Examples

Default: Button shows selected range with presets available. Always has a default presets with the most commonly used date range.

Period picker consists of two main elements:

Button (with clock icon) using two lines:
- Line 1: Active preset or custom date range.
- Line 2: Start and end dates of selected range
Popover (triggered by button click) with:
- Preset tabs (e.g., "Last 7 Days," "Last Month")
- Interactive calendar view for custom range selection

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return <PeriodPicker aria-label="Select period" value={period} onChange={setPeriod} />;

#Usage with hidden presets

Used when preset data is unavailable, focusing on custom selection.

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return (
	<PeriodPicker
		aria-label="Select period"
		value={period}
		onChange={setPeriod}
		hiddenPresets={[
			PeriodType.LastSevenDays,
			PeriodType.LastFourteenDays,
			PeriodType.LastThirtyDays,
			PeriodType.Last365Days,
		]}
	/>
);

#Usage with condensed variant

Button (with clock icon) displaying selected range in one line.

CodeHTML output

const [period, setPeriod] = React.useState<PeriodPickerValue | null>({
	start: new Date(2023, 4, 1),
	end: new Date(2023, 4, 31),
	type: PeriodType.Custom,
});

return <PeriodPicker aria-label="Select period" value={period} onChange={setPeriod} condensed />;

#Properties

CodePropsHTML output

Property	Description	Defined	Value
valueRequired	`\| object`The value of the component	YesNo
onChangeRequired	`function`Callback that is called when the value changes	YesNo
minDateOptional	`date`	YesNo
maxDateOptional	`date`	YesNo
hiddenPresetsOptional	`literal-union[]`	YesNo
condensedOptional	`boolean`	YesNo	truefalse
disabledOptional	`boolean`Whether the component is disabled	YesNo	truefalse
aria-labelOptional	`string`Label of the form control	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
periodButtonVariantOptional	`"borderless" \| "ctaDefault" \| "ctaPrimary" \| "ctaSecondary" \| "default" \| "destructive" \| "primary" \| "secondary"`How should the button look	YesNo
periodButtonSizeOptional	`"large" \| "medium" \| "small"`Controls the size of the button - defaults to medium	YesNo
periodButtonStyleOptional	`object`Add inline style for the button only if necessary	YesNo
strategyOptional	`"absolute" \| "fixed"`Position popover using fixed or absolute	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo
onBlurOptional	`function`Callback for onBlur event	YesNo

#Guidelines

#Best practices

#General

Use PeriodPicker when

Users need to define a specific date range for filtering, reporting, or analysis. .

#Placement

PeriodPicker is typically used in the following places:

Form: Select time period for report progress (e.g Edit scheduled report)
Filter: Filter data in charts to track progress of issues (e.g Accessibility overview)

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your PeriodPicker to existing components for visual consistency.
Always offer a logical default range (e.g., "Last 7 Days") to streamline common tasks.
Visually indicate the active range at all times.
Visually connect the selected dates within the calendar view to the button's display.
Prevent users from selecting invalid ranges (e.g., end date before start date). Provide clear error messages if needed.

#Do not use when

Users only need to select a single date (use a Date picker instead).

#Accessibility

For designers

Clear labels and instructions.

For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

Use concise labels for presets (e.g., "Last Month").